Call Fabric

Call Fabric is the embodiment of SignalWire's vision for Programmable Unified Communications. It is effectively a new paradigm in communications, designed to streamline usage and development across all communication types.

Check out our What is Call Fabric? guide to learn more, and make sure to read our CEO's blog to see how it the next evolution from FreeSWITCH!

The following section details the mechanisms available in the SignalWire browser SDK (@signalwire/js) to take advantage of the Call Fabric architecture.

Installation

Call Fabric is available in the SignalWire Browser SDK (@signalwire/js) versions 3.27.0 and later.

If your project uses a package manager, the Browser SDK can be installed like so:

npm
Yarn
pnpm

npm install @signalwire/js

yarn add @signalwire/js

pnpm add @signalwire/js

It is also available through our CDN and can be included directly into the <head> section of your webpage.

<script src="https://cdn.signalwire.com/@signalwire/js"></script>

Once installed, you can take advantage of the new capabilities that Call Fabric enables by instantiating a SignalWire Client, like so:

<script type="text/javascript" src="https://cdn.signalwire.com/@signalwire/js"></script>
<script>
  async function main() {
    const client = await SignalWire.SignalWire({
      token: "<TOKEN>",
    });
  }
</script>

The access token is received after the Call Fabric subscriber completes the OAuth2 flow and successfully logs in. Learn more at the Authentication section further below.

Concepts

Resources

Resources are the primary entities for communication within SignalWire. Resources include: Subscribers SWML Scripts, SignalWire AI Agents, Video-Rooms, SIP Endpoints, etc.

Subscribers

Subscribers represent the end-users within SignalWire. They are the endpoints of communication, capable of receiving or initiating calls, messages, and other forms of interaction.

SignalWire allows subscribers to switch from one type of communication to another. For example, switching from a phone call into a video-room to a web-based video call.

You can create Subscribers and Resources in the Resource section of your SignalWire Dashboard, or with a HTTP POST request:

curl --location --request POST 'https://spacename.signalwire.com/api/fabric/subscribers' \
--user "project_id:api key" \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "[the subscriber email]",
    "password": "[the subscriber password]"
}'

Addresses

Each resource and subscriber is uniquely identified by an addresses which can be called, sent messages to, or interacted with in some other way.

The address is composed of two parts: "/context/name"

Context: A identifier that indicates in which context the resource is located.
Name: The name is the unique identifier for the resource.

For example, the address for a Subscribers resource named Alice in the public context would be /public/Alice.

Authentication

As explained in the Subscribers section above, Subscribers represent the end-users within SignalWire, thus usually actions are performed on behalf of the subscriber.

So, when using the SignalWire Client, you will need a Subscriber's token to authenticate your requests. Usually, that token is obtained when the subscriber logs in using the OAuth2 flow described further below. But your server applications can perform actions on behalf of the subscriber by using getting a token using the REST API.

REST API token authentication

You can obtain authentication tokens directly through the REST API. The following endpoints are available for token generation:

Create a guest token

Generate a limited-access token for guest access to specific Fabric addresses.

Create a subscriber invite token

Generate a token to access resources associated with a specific subscriber on behalf of the subscriber.

Create a new subscriber and a token

Create a new subscriber and get their token in a single request.

info

For browser-based applications, we recommend using the OAuth2 flow to authenticate subscribers and obtain tokens. See Authenticate subscribers using OAuth2 below for details.

Using the token

The endpoints return a JSON object containing a token property. Use this token to initialize the SignalWire Client:

import { SignalWire } from "@signalwire/js";

const client = await SignalWire({
  token: "eyJhbGciOiJIUzI1NiIs..."
});

Authenticate subscribers using OAuth2

When you create a Subscriber, you assign them a username (email) and a password. These credentials can be used authenticate the subscriber using the standard OAuth2 flow with PKCE. For OAuth2, you can use tools like odic-client-ts or react-native-app-auth.

You can also use this node.js script from SignalWire Community to get a token for a subscriber.

info

Currently, the only way to get a client ID for the OAuth2 flow is through the SignalWire Support team.

oidc-client-ts
react-native-app-auth

import { UserManager, WebStorageStateStore } from "oidc-client-ts";

const config = {
  authority: "x", // dummy authority
  metadata: {
    issuer: "https://id.fabric.signalwire.com/",
    authorization_endpoint: "https://id.fabric.signalwire.com/login/oauth/authorize",
    token_endpoint: "https://id.fabric.signalwire.com/oauth/token",
  },
  client_id: "<Your_Fabric_Client_id>",
  redirect_uri: "https://redirect_uri",
  response_type: "code",
  userStore: new WebStorageStateStore({ store: window.localStorage }),
};

const userManager = new UserManager(config);

await userManager.signinRedirect();

import { authorize } from "react-native-app-auth";

const config = {
  serviceConfiguration: {
    authorizationEndpoint: "https://id.fabric.signalwire.com/login/oauth/authorize",
    tokenEndpoint: "https://id.fabric.signalwire.com/oauth/token",
  },

  clientId: "<Your_Fabric_Client_id>",
  redirectUrl: "your app's redirect uri",
  clientAuthMethod: "post",
};

const result = await authorize(config);

A complete example is presented below. Assuming that this page is npx served at the address http://localhost:3000, this script takes the subscriber through the OAuth2 login flow, and uses the access token received to fetch the subscriber's registration details from SignalWire.

index.html
<html>
  <head>
    <style>
      .loading > button { display: none }
      .loading::after { content: "Loading..." }
    </style>
  </head>

  <body>
    <div id="container" class="loading">
      <button onclick="userManager.signinRedirect()">Log In</button>
    </div>

    <script src="https://cdn.jsdelivr.net/npm/oidc-client-ts@3.0.1/dist/browser/oidc-client-ts.min.js"></script>
    <script src="https://cdn.signalwire.com/@signalwire/js"></script>
    <script>
      const container = document.getElementById("container");

      const config = {
        authority: "x", // dummy authority
        metadata: {
          issuer: "https://id.fabric.signalwire.com/",
          authorization_endpoint: "https://id.fabric.signalwire.com/login/oauth/authorize",
          token_endpoint: "https://id.fabric.signalwire.com/oauth/token",
        },
        client_id: "<Your_Fabric_Client_id>",
        redirect_uri: "http://localhost:3000", // assuming this page is being served at port 3000 of localhost
        response_type: "code",
        userStore: new oidc.WebStorageStateStore({ store: window.localStorage }),
      };

      const userManager = new oidc.UserManager(config);

      async function checkForRedirect() {
        try {
          const user = await userManager.signinRedirectCallback();
          if (user) {
            // the oauth flow completed successfully, we can now use Call Fabric features using the access token.
            await getSubscriberInfo(user.access_token);
          }
        } catch (e) {
          // signinRedirectCallback failed; login flow hasn't been started yet. We'll show the Login button.
          container.classList.remove("loading");
        }
      }

      async function getSubscriberInfo(token) {
        const client = await SignalWire.SignalWire({ token });
        const subInfo = await client.getSubscriberInfo();

        container.classList.remove("loading");
        container.innerText = `Hello, ${subInfo.first_name}`;
      }

      // We want to check if the user was redirected here from the subscriber login flow,
      // or if the came here directly from the browser. If the user came directly from the 
      // browser, we show a Login button. If they were redirected here, we allow oidc-client-ts
      // to finish the flow and get the access token.
      checkForRedirect();
    </script>
  </body>
</html>

Core components

SignalWire client

The main entry point for Call Fabric applications. The client provides access to all Fabric functionality including calls, messaging, and device management.

SignalWire client

Learn how to instantiate and use the SignalWire client for unified communications

Address management

Addresses are unique identifiers for different types of entities in the system, including subscribers, rooms, and other resources.

Address management

Discover how to work with addresses for subscribers, rooms, and other resources

Chat and messaging

Real-time messaging capabilities for sending and receiving messages, managing conversations, and handling chat events.

Chat and messaging

Send and receive messages, manage conversations, and handle real-time chat

Conversation management

Advanced conversation features for managing message history, subscriptions, and conversation metadata.

Conversation management

Manage conversations, send messages, and handle real-time conversation events

Advanced features

Push notifications

Configure and handle push notifications for incoming calls when the client is offline.

Push notifications

Configure and handle push notifications for incoming calls

Utility functions

Helper functions for video element management and other common tasks.

Utility functions

Use utility functions for video element management and other common tasks

API reference

Client parameters

The SignalWire client accepts the following parameters:

Parameter	Type	Required	Description
`token`	`string`	Yes	The access token for the subscriber
`rootElement`	`HTMLElement`	No	HTML element to display video streams
`incomingCallHandlers`	`IncomingCallHandlers`	No	Callback functions for incoming calls
`userVariables`	`Record<string, any>`	No	Arbitrary variables transparent to FreeSwitch
`host`	`string`	No	SignalWire host URL
`project`	`string`	No	SignalWire project ID
`contexts`	`string[]`	No	SignalWire contexts (e.g., 'home', 'office')
`topics`	`string[]`	No	Alias for contexts with higher priority
`logLevel`	`string`	No	Logging level ('error', 'trace', 'debug', 'info', 'warn', 'silent')
`onRefreshToken`	`() => Promise<string>`	No	Callback to fetch new authentication token

Client methods

The SignalWire client provides the following core methods:

Call management

dial(params) - Dial a resource and connect the call
reattach(params) - Reattach to a previous call if not disconnected
online(incomingCallHandlers) - Mark client as online to receive calls
offline() - Mark client as offline to stop receiving calls

Device management

registerDevice(params) - Register device for push notifications
unregisterDevice(params) - Unregister device from push notifications

Information retrieval

getSubscriberInfo() - Retrieve current subscriber information
updateToken(token) - Update authentication token

Push notification handling

handlePushNotification(params) - Handle incoming call via push notification

Connection management

disconnect() - Disconnect from SignalWire network

Namespaces

The client provides access to several namespaces for organized functionality:

Address namespace

getAddresses(options) - Get list of addresses
getAddress(options) - Get specific address details

Chat namespace

getMessages(options) - Get chat messages for an address
subscribe(options) - Subscribe to chat messages
sendMessage(options) - Send a chat message
join(options) - Join a conversation

Conversation namespace

getConversations() - Get list of conversations
getMessages(options) - Get conversation messages
getConversationMessages(options) - Get messages for specific conversation
subscribe(callback) - Subscribe to conversation events
sendMessage(options) - Send conversation message
join(options) - Join a conversation

Get started

Quick start

Learn how to instantiate and configure the SignalWire client

Make your first call

Dial to addresses and handle incoming calls

Send messages

Send and receive real-time messages

Popular guides

Push notifications

Configure and handle push notifications for incoming calls

Utility functions

Use utility functions for video element management and other common tasks

Installation​

Concepts​

Resources​

Subscribers​

Addresses​

Authentication​

REST API token authentication​

Create a guest token

Create a subscriber invite token

Create a new subscriber and a token

Using the token​

Authenticate subscribers using OAuth2​

Core components​

SignalWire client​

SignalWire client

Address management​

Address management

Chat and messaging​

Chat and messaging

Conversation management​

Conversation management

Advanced features​

Push notifications​

Push notifications

Utility functions​

Utility functions

API reference​

Client parameters​

Client methods​

Call management​

Device management​

Information retrieval​

Push notification handling​

Connection management​

Namespaces​

Address namespace​

Chat namespace​

Conversation namespace​

Get started​

Quick start

Make your first call

Send messages

Popular guides​

Push notifications

Utility functions

Installation

Concepts

Resources

Subscribers

Addresses

Authentication

REST API token authentication

Using the token

Authenticate subscribers using OAuth2

Core components

SignalWire client

Address management

Chat and messaging

Conversation management

Advanced features

Push notifications

Utility functions

API reference

Client parameters

Client methods

Call management

Device management

Information retrieval

Push notification handling

Connection management

Namespaces

Address namespace

Chat namespace

Conversation namespace

Get started

Popular guides